ATOM Documentation

Mobile & Menu Bar Deployment Guide

🚀 Deployment Strategy for Mobile UI & Menu Bar Companion

This guide covers deploying the mobile-responsive UI and menu bar companion features to production.

---

Phase 1: Pre-Deployment Checklist

Code Quality

• [x] All TypeScript errors fixed
• [x] No console warnings
• [x] Components tested on multiple viewports
• [x] Swipe gestures working
• [x] Voice commands implemented (stub)

Testing

• [x] E2E tests created (35 tests)
• [x] Component tests written
• [x] Mobile viewports tested
• [ ] Run full test suite and ensure 100% pass rate
• [ ] Real device testing (iOS Safari, Chrome Android)

Documentation

• [x] Icon design guide created
• [x] Implementation documentation complete
• [x] Testing guide written
• [x] Swipe functionality documented
• [ ] Voice wake activation guide (this doc)

---

Phase 2: Staging Deployment

Step 1: Create Feature Branch

git checkout -b feature/mobile-menu-bar-companion
git push origin feature/mobile-menu-bar-companion

Step 2: Deploy to Staging

# If using Cloud Console
atom-cli deploy --env staging

# If using Vercel/Netlify
vercel deploy --env=staging

Step 3: Staging Tests

1. **URL**: https://staging.atom.ai
2. **Test on real mobile devices**:

• iPhone (Safari)
• Android (Chrome)
• iPad

1. **Test menu bar** (if available):

• Install desktop app
• Verify activity streaming
• Test quick actions

Step 4: Performance Validation

# Run Lighthouse CI
npm run lighthouse:ci

# Check metrics
# Target: Mobile score > 90
# Performance > 90
# Accessibility > 90
# Best Practices > 90

---

Phase 3: Production Deployment

Step 1: Final Testing

# Run full E2E test suite
npx playwright test

# Run component tests
npm test

# Check bundle size
npm run build
# Verify build output < 200KB per page

Step 2: Create Release

# Tag release
git tag -a v1.4.0-mobile-menu-bar -m "Mobile UI & Menu Bar Companion"
git push origin v1.4.0-mobile-menu-bar

Step 3: Deploy to Production

# Production deployment
atom-cli deploy --env production

# Or Vercel
vercel deploy --prod

Step 4: Smoke Tests

• [ ] Homepage loads on mobile
• [ ] Bottom navigation visible
• [ ] Hamburger menu works
• [ ] All pages accessible
• [ ] No console errors
• [ ] WebSocket connects (menu bar)

---

Phase 4: Monitoring Setup

Application Performance Monitoring (APM)

1. Frontend Metrics

// Track mobile-specific metrics
if (window.innerWidth < 768) {
  // Track bottom navigation render time
  performance.mark('mobile-nav-start');
  // ... navigation renders
  performance.mark('mobile-nav-end');
  performance.measure('mobile-nav-render', 'mobile-nav-start', 'mobile-nav-end');
}

// Track swipe gestures
function trackSwipeGesture(direction: 'left' | 'right') {
  gtag('event', 'swipe_gesture', {
    'direction': direction,
    'viewport_width': window.innerWidth,
  });
}

2. Backend Metrics (Activity Streaming)

# Track WebSocket connections
redis.incr('menu_bar:connections:active')
redis.incr(f'menu_bar:connections:tenant:{tenant_id}')

# Track activity events
redis.incr(f'activity:events:{tenant_id}')

# Set up alerts
# Alert if: connections > 1000, errors > 5%

Real User Monitoring (RUM)

Implement Google Analytics

// lib/analytics.ts
export function trackMobileEvent(action: string, label: string) {
  if (typeof window !== 'undefined' && (window as any).gtag) {
    (window as any).gtag('event', action, {
      'event_category': 'Mobile UI',
      'event_label': label,
      'viewport_width': window.innerWidth,
    });
  }
}

// Track bottom navigation clicks
trackMobileEvent('navigation', 'bottom_nav_click');

// Track hamburger menu opens
trackMobileEvent('menu', 'hamburger_open');

// Track swipe gestures
trackMobileEvent('gesture', `swipe_${direction}`);

Health Checks

Frontend Health Endpoint

// GET /api/mobile/health
export async function GET() {
  return {
    status: 'healthy',
    features: {
      mobileNavigation: true,
      hamburgerMenu: true,
      swipeGestures: true,
      voiceCommands: false, // Coming soon
    },
  };
}

Backend Health Check

# GET /api/activity/health
{
  "status": "healthy",
  "tenant_id": "uuid",
  "redis": "connected",
  "active_connections": 42,
  "streaming_available": true
}

---

Phase 5: Rollback Plan

If Issues Detected

Immediate Rollback

# Rollback deployment
atom-cli deployments rollback

# Or rollback to previous git commit
git revert HEAD
git push origin main
atom-cli deploy

Feature Flags (Optional)

// Enable/disable mobile features
const MOBILE_FEATURES_ENABLED = process.env.NEXT_PUBLIC_MOBILE_ENABLED === 'true';

if (MOBILE_FEATURES_ENABLED && isMobile) {
  return <MobileNavigation />;
}

---

Phase 6: Success Metrics

Key Performance Indicators (KPIs)

Mobile UI Metrics

Menu Bar Metrics

How to Track

Google Analytics Dashboard

1. Navigate to: Behavior → Events
2. Filter by: Event Category = "Mobile UI"
3. View: Total events, unique events

Backend Metrics

# Redis CLI
redis-cli

# Check active connections
GET menu_bar:connections:active

# Check tenant-specific connections
KEYS menu_bar:connections:tenant:*

# Check activity event counts
KEYS activity:events:*

---

Phase 7: Post-Deployment Tasks

1. Monitor Error Rates

# Check error tracking (Sentry, LogRocket, etc.)
# Look for: Mobile-specific errors, WebSocket failures

2. Collect User Feedback

// Add feedback widget for mobile users
if (isMobile && Math.random() < 0.1) { // 10% of users
  showFeedbackWidget({
    question: 'How is the mobile experience?',
    rating: '1-5 stars',
    comment: true,
  });
}

3. Iterate Based on Data

• Analyze swipe gesture usage
• Check bottom navigation click patterns
• Review hamburger menu open rates
• Identify friction points

---

Environment Variables

Required for Production

# Mobile feature flags
NEXT_PUBLIC_MOBILE_ENABLED=true
NEXT_PUBLIC_VOICE_COMMANDS_ENABLED=false # Future

# WebSocket configuration
NEXT_PUBLIC_WS_URL=wss://api.atom.ai
WS_RECONNECT_DELAY=1000
WS_MAX_RECONNECT_ATTEMPTS=5

---

Troubleshooting

Common Issues

Issue: Bottom navigation not visible

**Fix**: Check viewport width < 768px, verify CSS classes

Issue: Swipe gestures not working

**Fix**: Ensure @use-gesture/react installed, check browser console

Issue: WebSocket connection fails

**Fix**: Check Redis status, verify JWT token, check CORS settings

Issue: Voice commands not recognized

**Fix**: Requires HTTPS, check browser support, verify permissions

Debug Commands

# Check mobile viewport
window.innerWidth
window.innerHeight

# Check WebSocket connection
ws = new WebSocket('wss://api.atom.ai/api/activity/stream?token=XXX')
ws.onopen = () => console.log('Connected')
ws.onerror = (e) => console.error('Error:', e)

# Check speech recognition support
'SpeechRecognition' in window || 'webkitSpeechRecognition' in window

---

Deployment Verification

Post-Deployment Checklist

• [ ] Homepage loads on mobile devices
• [ ] Bottom navigation visible on mobile
• [ ] Desktop sidebar hidden on mobile
• [ ] Hamburger menu opens/closes
• [ ] All navigation links work
• [ ] Swipe gestures functional
• [ ] No console errors
• [ ] Lighthouse score > 90
• [ ] WebSocket connects (menu bar)
• [ ] Activity events streaming
• [ ] Health checks passing
• [ ] Monitoring alerts configured

---

Rollout Strategy

Phased Rollout

Week 1: Staging

• Deploy to staging environment
• Internal testing team validates
• Fix critical bugs

Week 2: Beta (10% of users)

• Feature flag: enable for 10% of users
• Monitor metrics closely
• Collect feedback

Week 3: General Availability (50%)

• Enable for 50% of users
• Continue monitoring
• Address performance issues

Week 4: Full Rollout (100%)

• Enable for all users
• Normal monitoring mode
• Plan next iteration

---

Maintenance

Regular Tasks

• [ ] Weekly: Review mobile usage metrics
• [ ] Weekly: Check WebSocket connection health
• [ ] Monthly: Update browser compatibility matrix
• [ ] Quarterly: Audit mobile performance

Known Limitations

• Voice commands: macOS only initially
• Swipe gestures: May not work on all browsers
• WebSocket: Requires stable connection
• Menu bar: Desktop app only (not web)

---

Support Contacts

• **Documentation**: See /docs/ directory
• **Issue Tracker**: GitHub Issues
• **Team Slack**: #mobile-ui, #menu-bar channels

---

**Deployment Date**: 2025-02-05 (Target)

**Status**: Ready for Staging Deployment

**Risk Level**: Low (mobile UI only, no breaking changes)